refactor: extract album buffer from telegram bot - #162

What

Extracts the photo-album (media-group) buffering mechanics out of TelegramBot into a standalone AlbumBuffer class in a new telegram/album_buffer.py. Third and final PR in the cleanup series for telegram/bot.py (stacked on #161, which is stacked on #160 — please review/merge in order).

Why

Telegram delivers a multi-photo album as several separate messages sharing a media_group_id rather than one message, so the bot has to buffer them, wait for a short debounce window (or a max-wait cap) for the rest to arrive, then process them as one turn. That buffering logic (~150 lines: a buffer dict, debounce/max-wait timers, the _BufferedAlbum dataclass) was one of five distinct concerns bolted onto the same TelegramBot class identified in the original audit.

As with #161, the existing test coverage for this subsystem pokes TelegramBot's private attributes directly (bot._album_buffers, bot._flush_album(...), etc.) across a ~1300-line test class in test_telegram_bot.py, so the clean extraction required updating that test coverage too, per the earlier "full extraction + test rewrite" agreement. Turned out simpler than the settings-menu case: most of these tests are genuine end-to-end integration tests through TelegramBot._safe_handle_update (message arrives → buffered → flushed → turn processed → response sent) and only needed mechanical attribute-path updates, not a conceptual rewrite. Only 4 of ~30 tests were pure buffering-mechanics tests that made sense to move to their own file targeting AlbumBuffer directly.

Like #161, this is a relocation for separation of concerns, not a line-count reduction (that was #160's job) — bot.py shrinks by 118 lines, extracted into its own module plus a proportionally small new test file.

How

• New telegram/album_buffer.py: _BufferedAlbum dataclass and AlbumBuffer class owning the buffer dict, debounce/max-wait constants, and all buffering-mechanics methods, moved verbatim from TelegramBot. AlbumBuffer takes an on_flush callback invoked synchronously with the completed album — it owns no turn-processing or session logic itself.
• bot.py: TelegramBot.__init__ constructs self._album_buffer = AlbumBuffer(on_flush=self._on_album_flushed); the shared _update_counter (used to interleave cancellation ordering between album and non-album turns for the same conversation) stays on TelegramBot and is threaded into add_message(message, seq) explicitly, since it can't be split across two counters without breaking that ordering. stop() now calls await self._album_buffer.shutdown(). _process_flushed_album and _handle_album_turn (the actual turn-processing business logic — session identity, downloading photos, running the ADK turn) stay on TelegramBot since they need its session/turn machinery; only the buffering mechanics moved.
• Removed ~150 lines from bot.py (1500 → 1382 lines); no behavior change, verified by porting every existing test case.
• Test split: tests/test_telegram_album_buffer.py (new, 144 lines) covers AlbumBuffer's buffering state machine in isolation (cleanup branches, debounce/max-wait triggering flush, already-processed guard). tests/test_telegram_bot.py keeps its ~26 end-to-end album integration tests, updated to the new attribute paths (bot._album_buffer._buffers, bot._album_buffer._flush(...), bot._album_buffer.cleanup(...), bot._album_buffer._max_wait(...), and the _BufferedAlbum import moved to blacki.telegram.album_buffer).

Tests

• pytest tests/test_telegram_album_buffer.py tests/test_telegram_bot.py -q — 242 passed
• pytest -q (full suite) — 1560 passed, 1 skipped
• ruff check / ruff format --check on all changed/new files — clean
• mypy on src/blacki/telegram/ — clean